<html>
<head>
<title>User Manual: Feeds</title>
<link href="./page.css" rel="stylesheet" type="text/css"/>
<link href="./olive.css" rel="stylesheet" type="text/css"/>
<link href="./manual.css" rel="stylesheet" type="text/css"/>
</head>
<body>

<h1>4. Feeds</h1>
<p>
(Setting Options) <a href="options.html">Prev</a> | <a href="index.html">Index</a> | <a href="dotdir.html">Next</a> (Dotdir)
</p>
<hr/>

<h2 id="s10">4.1 Adding Feeds</h2>
<p>
  Feeds are added to Olive via the Add New Feed dialog, which is
  invoked by pressing '<code>C-a</code>'.
</p>
<pre class='screen'>
  .-<span class='rv'>[ Add New Feed ]</span>-----------------------------------------.
  |                                                          |
  | Location: <span class='rv'>[                                            ]</span> |
  |                                                          |
  | Nickname: <span class='rv'>[                ]</span>                             |
  |                                                          |
  |           [ ] Flag this feed                             |
  |                                                          |
  |           [ ] Force-poll this feed                       |
  |                                                          |
  |                                        < OK > < Cancel > |
  |                                                          |
  '----------------------------------------------------------'
</pre>
<p>
  Fill out the form and select <code>OK</code> to attempt to store the
  feed. It will be tested for network availablility, and if Olive can
  fetch the feed, it will be added. If the feed cannot be found or
  fetched, an error will be displayed and it will <em>not</em> be
  added to the feed list.
</p>
<p>
  The <code>Location</code> field holds the URL of the
  feed.
</p>
<p>
  <code>Nickname</code> is a short (16-character maximum) display name
  which will be used in the <a href="./news.html#s12">List Pane</a>.
</p>
<p>
  Toggling "<code>Flag this feed</code>" causes the feed to
  be <em>flagged</em>, as described
  in <a href="./news.html#s40">Section 2.4</a>.
</p>
<h3 id="s11">4.1.1 Enabling Force-poll</h3>
<p>
  The "<code>Force-poll this feed</code>" option enables an on-demand
  override of normal <a href="#s40">feed polling procedure</a>. It
  causes TTL checks to be skipped and treats a <code>304 Not
  Modified</code> as a <code>200 OK</code>, causing a fetch of the
  feed regardless of elapsed time or the actual modification status of
  that feed. This should only be used when there is a problem getting
  a feed which you know has changed, but which is not updating for
  whatever reason.
</p>

<h2 id="s20">4.2 Editing Feeds</h2>
<p>
  To change information about a feed, first invoke the Edit Feeds
  dialog by pressing '<code>C-e</code>'. You will be presented with a
  list of feeds and their current statuses, ordered alphabetically by
  feed nickname.
</p>
<pre class='screen'>
  .-<span class='rv'>[ Edit Feeds ]</span>-------------.
  |                            |
  |  <b>Feed</b>              <b>Status</b>  |
  |                            |
  |  ATC               f--   <span class='rv'>#</span> |
  |  <span class='rv'>BBC News          ---  </span> <span class='rv'>#</span> |
  |  bda               f--   <span class='rv'>#</span> |
  |  code4lib          --d   <span class='rv'>#</span> |
  |  Dru               f--   <span class='rv'>#</span> |
  |  Groklaw           ---   <span class='rv'>#</span> |
  |  Kate              fp-   <span class='rv'>#</span> |
  |  LtU               ---   | |
  |  OBSD Security     ---   | |
  |  Olive             -p-   | |
  |                            |
  |                    < OK >  |
  |                            |
  '----------------------------'
</pre>
<p>
  The three statuses are:
</p>
<ul>
  <li>
    <em>Flagged</em>, indicated by an '<code>f</code>' in the first
    status column.
  </li>
  <li>
    <em>Force-polled</em>, indicated by a '<code>p</code>' in the
    second status column.
  </li>
  <li>
    <em>Dormant</em>, indicated by a '<code>d</code>' in the
    third status column.
  </li>
</ul>
<p>
  It is possible for a single feed to have multiple statuses
  set. Statuses not set display a hyphen.
</p>
<p>
  Use the arrow keys to move through the list and select a feed
  with <code>Enter</code>. This will bring up the edit dialog for that
  feed.
</p>
<pre class='screen'>
  .-<span class='rv'>[ Edit BBC News ]</span>----------------------------------------.
  |                                                          |
  | Location: <span class='rv'>[http://newsrss.bbc.co.uk/rss/newsonline_wor$]</span> |
  |                                                          |
  | Nickname: <span class='rv'>[BBC News       ]</span>                              |
  |                                                          |
  |           [ ] Flag this feed                             |
  |                                                          |
  |           [ ] Force-poll this feed                       |
  |                                                          |
  |           [ ] Feed is dormant                            |
  |                                                          |
  |                                        < OK > < Cancel > |
  |                                                          |
  '----------------------------------------------------------' 
</pre>
<p>
  Everything here works just <a href="#s10">as above</a>, except for
  the addition of the last checkbox. Feeds are tested for network
  accessibility before changes are applied.
</p>
<h3 id="s21">4.2.1 Dormant Feeds</h3>
<p>
  Dormant feeds are never polled, even if they are also marked as
  being force-polled. If Olive sets a feed dormant due to errors, you
  can come here to unset that flag. The dormant flag will <em>not</em>
  be unset if Olive cannot fetch the feed.
</p>

<h2 id="s30">4.3 Removing Feeds</h2>
<p>
  To change information about a feed, first invoke the Remove Feeds
  dialog by pressing '<code>C-r</code>'. You will be presented with a
  list of feeds and their current statuses, ordered alphabetically by
  feed nickname.
</p>
<pre class='screen'>
  .-<span class='rv'>[ Remove Feeds ]</span>---------------.
  |                                |
  |  <b>Sel</b> <b>Feed</b>              <b>Status</b>  |
  |                                |
  |  [ ] ATC               f--   <span class='rv'>#</span> |
  |  [ ] <span class='rv'>BBC News          ---  </span> <span class='rv'>#</span> |
  |  [ ] bda               f--   <span class='rv'>#</span> |
  |  [ ] code4lib          --d   <span class='rv'>#</span> |
  |  [ ] Dru               f--   <span class='rv'>#</span> |
  |  [ ] Groklaw           ---   <span class='rv'>#</span> |
  |  [ ] Kate              fp-   <span class='rv'>#</span> |
  |  [ ] LtU               ---   | |
  |  [ ] OBSD Security     ---   | |
  |  [ ] Olive             -p-   | |
  |                                |
  |                        < OK >  |
  |                                |
  '--------------------------------'
</pre>
<p>
  Simply go through the list, using <code>Enter</code> to select feeds
  for deletion, then select '<code>OK</code>' to remove those
  feeds. Their stories will be removed from the story database, their
  feed and cache files will be deleted from disk, and their
  information will be purged from Olive's feed list.
</p>


<h2 id="s40">4.4 Polling Feeds</h2>
<p>
  Feeds are polled (checked for updates) every time the period
  specified in the <a href="./options.html#s30">Poll Wait</a> option
  elapses. You can request an early poll with the '<code>p</code>'
  key. Feeds which are marked as <a href="#s11">forced</a> can be
  fetched on demand via the '<code>P</code>' key.
</p>
<p>
  Here is the proceedure Olive follows for polling non-forced feeds.
</p>
<ul>
  <li>
    Each feed's last-checked time is subtracted from the current time
    and the difference is compared to that feed's TTL (time-to-live)
    value.
  </li>
  <li>
    If the time difference is less than the TTL, no further action is
    taken for that feed.
  </li>
  <li>
    If the time difference is greater than or equal to the TTL, the
    feed is polled.
  </li>
  <li>
    A polled feed is first pinged, to check its status.
  </li>
  <li>
    If the ping (not a literal ICMP ping, but a HTTP HEAD request)
    comes back as a <code>304 Not Modified</code>, no further action
    is taken for that feed.
  </li>
  <li>
    If the ping indicates success, the feed is fetched and processed.
  </li>
  <li>
    If the ping comes back as <code>403 Forbidden</code> or <code>410
    Gone</code>, the feed will be marked <a href="#s21">dormant</a>
    and you will be notified of this via a dialog box.
  </li>
  <li>
    If the ping indicates some other error condition, information is
    logged to the error log and the TTL is modified (first dropped,
    then incrementally lengthened on successive errors).
  </li>
  <li>
    If a feed has 5 successive failures, it will be
    marked <a href="#s21">dormant</a> and you will be notified of this
    via a dialog box.
  </li>
</ul>


<hr/>
<p>
(Setting Options) <a href="options.html">Prev</a> | <a href="index.html">Index</a> | <a href="dotdir.html">Next</a> (Dotdir)
</p>
<hr/>
<p>
$Id: feeds.html 419 2006-02-03 19:33:50Z mdxi $
</p>
</body>
</html>
